The Pattern Structure (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /

Chapter 3 - Geometric Styles / Geometric Styles Reference

The Pattern Structure
With QuickDraw GX, you can specify that certain shapes be patterned. For shapes with solid shape fills, QuickDraw GX fills the shape by repeating a pattern shape that you specify, over a grid that you specify.
You can also pattern shapes with framed shape fills. For example, imagine a rectangle shape with the closed-frame shape fill and a pen width of 20. If you patterned this rectangle, QuickDraw GX would fill the frame of the rectangle with the pattern. See the section "Adding a Pattern to a Shape" on page 3-86 for examples.
QuickDraw GX uses the pattern property of a shape's style object to store information about how to pattern the shape.
You use the pattern structure when specifying pattern information (using the GXSetStylePattern or GXSetShapePattern functions) and when retrieving pattern information (using the GXGetStylePattern or GXGetShapePattern functions).
The pattern structure is defined by the gxPatternRecord data type:
struct gxPatternRecord {
   gxPatternAttribute attributes; 
   gxShape            pattern;   
   gxPoint            u;          
   gxPoint            v;         
};
Field Description

attributes
Modifies the behavior of the pattern. The next section, "Pattern Attributes," describes the gxPatternAttribute flags in detail.
pattern
Specifies the shape that makes up the pattern. You must use shapes in their primitive form for the pattern shape. (Primitive shapes are described in detail in Chapter 4, "Geometric Operations," in this book.) You may not use text shapes, layout shapes, or picture shapes as the pattern shape. However, you may use framed shape shapes and shapes with an inverse shape fill. You may also use bitmap shapes with any pixel size as long as the bitmap shape does not contain color profile information.

QuickDraw GX considers only the geometric properties (the shape type, the shape fill, and the shape geometry) of the shape specified by the pattern field. QuickDraw GX ignores the owner count, shape tags, and shape attributes properties and the style, ink, and transform objects of the pattern shape.
u
One of a pair of vectors that determine how QuickDraw GX places the pattern shape. This field, along with the v field, defines the pattern grid.
v
The other of the pair of vectors that describe how QuickDraw GX places the pattern shape. This field, along with the u field, defines the pattern grid.
The u and v fields together form a pair of vectors that define the pattern grid, which determines where QuickDraw GX places the pattern shape. The vectors define a grid of parallelograms and QuickDraw GX draws a pattern shape at every intersection in this grid.
The vectors specified by the u and v fields do not need to be any order, but they must point in different directions--that is, they may not lie on the same line. If you specify u and v vectors that are parallel, a pattern_lattice_out_of_range error results.

Optimization Note
QuickDraw GX draws bitmap patterns very quickly--that is, nearly as fast as a nonpatterned fill--if the u and v vectors place the patterns in a rectangular grid the size of the bitmap.
See "Patterns" beginning on page 3-31 for more information about patterns and the pattern grid, and "Adding a Pattern to a Shape" on page 3-86 for an example of using patterns.